The objective of this chapter’s tutorial is to explore the features of the Prograph editor and interpreter*894*, especially online help facilities and features that help you inspect and edit Prograph applications while they are running.
Prograph’s online information sources are invaluable for helping you learn and use the language: you are freed from relying on the Reference manual much more quickly than with other programming languages. In addition, the Prograph interpreter has been designed to help you see and understand what your program is doing at all times. Error*321* reports identify and explain any problems with your code and quickly locate the exact place where a correction is required.
t Online Help*780*
u Launch Prograph by double-clicking the Prograph Classic application icon.
Balloon Help
*98*If you are running Macintosh System 7, you can turn Balloon Help on and get extensive help on Prograph menus, menu items, dialogs, and contents of editor windows, including case windows.
Message Preferences
*677*The most obvious source of online information in Prograph is the*634* Info menu.
 
The last item in this menu,*442* *783*Options…, *641*lets you configure a number of different default settings for the Prograph environment.
u Select*810* Options… *911*from the*436* Info menu. Click the*672* Error Messages and Warning Messages check boxes to select maximum support.
 
u Press Return to dismiss the Options… dialog.
With all Message Preferences settings checked, you get the most interactive help available. This mode is appropriate for those very new to Prograph and the Macintosh.
u Click anywhere in the Universal Methods window to activate it, if necessary. Command-click to create a new universal-method icon. The icon is white on black (red in color), indicating that it is selected.
u Select Cut Object from the Edit menu or press Option-Command-X. A Warning Message appears:
 
This Warning Message cautions you about cutting and deleting method and class icons. Having the Warning Messages option on can be very helpful until you are an experienced Prographer.
NOTE: Since most icon objects*767* in Prograph have two directly editable components—the icon itself and its text identifier—there are two sets of cut, copy, and paste functions in the Edit menu.
 
*597**598*The Cut,*282**221* *600*Copy*280*,*219* Paste,*603* *822*and*164* Clear *279*items perform familiar text-related operations on the text elements of an icon. Cut deletes the name of a selected method icon and puts the text on the clipboard. Selecting a second method icon and then doing a*285* Paste operation replaces the name of the selected method with the text on the clipboard. These operations are also useful for editing*1074* text in Prograph comments, in nongraphical Value window panes, in text-file windows, and in desk accessories opened within the Prograph environment.
*599**601*The separate Cut Object,*283**222* Copy Object,*220* *281*and*286* Paste Object *604**823*operate on the whole object, not the text. Prograph class, method, and persistent icons themselves can be cut, copied, and pasted. The keyboard Command-key equivalents for these operations are similar to their text-editing counterparts, except that you hold down the Option key with the Command key before pressing X, C, or V.
Delete Object *266**284**602*is similar to the Backspace function used to delete text —the object is removed and not placed on the clipboard. You can undo a Delete Object operation by choosing*289* *1118*Undo Delete.*607* Delete Object works on attribute icons and on roots and terminals of input bars, output bars, and operations within the case window of a method.*287* *945*Replicate Object*945* *605*performs a Copy Object and Paste Object in one quick action. It is especially useful in the window editor for repetitive tasks such as creating a number of like sized buttons.
u Confirm the intended Cut Object operation by pressing Return to dismiss the warning dialog.
Take a few minutes to experiment with creating and manipulating class, method, attribute, and persistent icons using the Edit menu items. Be sure to add a few comments*173* to some icons to explore the various text- and icon-editing functions.
While experimenting with the various cut, copy, and paste functions, you may find that you like the extra security of Warning Messages. If they seem to get in your way, return to the Options… dialog and click this option off. Leave the Error Messages option on, however, as you continue the tutorial.
u Command-click in the Classes window to create a new class and name it Anything. Click on the Anything class icon to highlight both the class icon and its text name.
u Press Command-C to Copy the name of this class to the clipboard.
u Command-click anywhere else in the Classes window to create a second new class.
u Press Command-V to Paste the text on the clipboard into the name field of this newest class. Press Return. An Error Message dialog is displayed:
 
u Press Return to dismiss this dialog. The Classes window activates with the duplicate name erased and the insertion bar flashing to indicate Prograph is waiting for a new and unique class name.
Error messages in Prograph are text explanations of problems that can occur as you develop your own Prograph applications. In this case, the message is short and self-explanatory — Prograph*884* class names must be unique. Some messages are longer: they explain the problem and suggest solutions.
Error messages can be automatically displayed, like this duplicate-name dialog, or they can be manually displayed following an*1034* error beep. How your error messages are displayed is a function of the Error Messages check box in the*811* Options… dialog. This option is currently checked.
u Open the*912* Options… dialog and click to deselect the Error Messages option check box. Press Return to dismiss the dialog.
u Repeat the Copy and Paste operation on the text of the class name from the Anything class icon to the second class icon. Press Return.
This time you hear two System*1033* beeps*102* and the duplicate name immediately disappears.
u Select Last Error… from the Info menu or press Command-L.
The error message dialog explaining the duplication of names is displayed as before. The type of error-message interaction does not affect the extent of the information that is made available to you when an error occurs. The effect is merely whether you see the message automatically or bring it up manually after hearing the audio signal.
While you are still new to Prograph, you may find that leaving the*322* Error Messages option selected is more efficient and helpful. After a while you will not need such extensive explanation, so turning Error Messages off may be preferred. For the duration of this tutorial:
u Open the*443* Options… *642*dialog and make sure that Error Messages and Warning Messages are checked (on).
NOTE: If you decide you want any combination of these options as your personal *786*default configuration every time you run Prograph, click*965* Save Settings rather than OK to dismiss the Options… dialog. Prograph then uses the current setting each time you launch Prograph. If you decide to change the configuration, simply return to the Options… dialog, make your changes, and select Save Settings again.
*639*The*441* Memory Status item*567* in the Info menu lets you monitor the amount of *932*RAM*915* currently*74* available for your Prograph programs.
 
The Free memory figure is the amount of memory available for normal operation. To prevent any unpleasant surprises, Prograph also sets aside a memory reserve. When there is no longer sufficient free memory, Prograph informs you that you are running on reserve:
 
If you have additional RAM that you want to dedicate to Prograph, quit from Prograph, click on the Prograph Classic icon on the desktop, choose Get Info from the File menu, and increase the Application Memory Size.
t Online Information
The Prograph environment has a large storehouse of information about both the Prograph language and the internal workings of the Macintosh. This information is accessible to you without your having to turn to references such as this manual and the multivolume*487* Inside Macintosh. While you will undoubtedly find reasons to refer to these external sources on occasion, you will find many of your information needs answered right within Prograph.
This rich source of online information is found in the ˙Info… dialog. The *150**456*Category pop-up menu*578*, in the upper left corner of this dialog, lists all of the different areas for which information is available.
u Open the ˙Info… dialog by selecting ˙Info… from the Info menu.
TIP: The ˙Info… dialog is a modeless dialog, which means that you do not need to dismiss it before doing something else. You can leave the dialog open for easy reference. In fact, you can have*743* multiple ˙Info… dialogs open. The default setting is a single ˙Info… dialog, but you can change this setting by clicking the check box for*742* Multiple Windows in the*812* Options… *913*dialog.
u Select*227**457* Data Types and click*103* boolean in the scrolling list of the data types that Prograph recognizes. The text pane in the right side of the dialog provides a brief explanation of the acceptable range of values and the usage of the boolean data type.
 
The Values: entry tells you that a boolean data value is either TRUE or FALSE (all caps). The Usage: note explains that a boolean data value is output by primitives that test an input, such as ≤ (less than or equal to) or the string? primitive. To get the most out of this and other ˙Info… *450*dialog text entries, you need to understand a few*759* notation conventions:
o A vertical bar, “|”, means OR.
TRUE | FALSE is TRUE or FALSE.
o A semicolon, “;”, is an item separator.
Window ; Button means the first item is a Window and the second item is a Button, as in the case of the input roots of a button’s click method.
o Square brackets, “[ ]”, enclose optional information.
Prompt ; Button1 ; [Button2 ; [Button3] ] means a primitive takes at least two and, optionally, three or four inputs. The leftmost input is a prompt string, and the second input is the string to name a required response button. Optionally two more inputs can be added, which the primitive interprets as names for buttons two and three. The primitive works with only the first two inputs. Likewise, it works with three or four inputs as indicated by the nested square brackets.
o An ellipsis*316*, “…”, indicates multiple identical items.
Element1 ; [ Element2 ; … ] indicates a primitive that takes at least one input and optionally as many inputs as you create on its operation icon. For example, the*818* pack *845*primitive takes at least one item, and as many items as you feed it, each on a separate input terminal. It returns a list containing all the input elements on its single output root. If there is a limit on how many such optional repeating items a primitive can take, the Usage: text entry tells you.
With these *218*conventions in mind, take a couple of minutes to review each of the entries in the scrolling list of data types. All objects you create in Prograph—instances of System classes and user-defined classes—are more or less complex data structures. Each has combinations of attributes, and each attribute maintains one of these data types as a value.
For example, the Person class created in the Grand Tour had a name attribute in which you stored a string type of data. If a weight attribute were added, you could store an integer or real number in it, depending on the numerical accuracy you wanted.
If you create a window using the Application Builder, the new instance of Window class stores a macintosh type *550*data value in the*1182* window record attribute. This macintosh data is called a “handle*403*” or a “pointer”. For example, the*1176* window record attribute might store the value WindowRecord@16#1DE414. If you are a Mac hacker, you probably delight in seeing this technical data value. The rest of us can safely ignore such intense-looking data values, which are primarily seen in the attributes of System*1035* classes that manage the window, menus, and events of the *557*Macintosh interface.
NOTE: Fortunately, Prograph and the Application Builder are designed to let you ignore the *541**861*low-level Macintosh details such as handles, pointers, stacks, heaps, and so on. Prograph manages this complexity for you, but access to the technical side of the Macintosh is available if you care to get at it. For most Prographers, when you see technical data specifications in an attribute of a System class instance, it is wiser to look but don’t touch.
To see which built-in operations can be performed on various types of data and on objects you create combining these types*228* of data, take a tour of Prograph’s primitives.
u Select Primitives from the ˙Info… dialog. Press the “f” key to jump to the beginning of the primitive entries that start with the letter “f.” Click the find-instance item. The text pane displays the specification of this primitive’s inputs and outputs and a brief explanation of its function:
 
Notice that the Types button is now activated. A click on this button toggles the text display to show the types of data that can be passed to and from the primitive on its roots and terminals. For example, the*372* find-instance *841*primitive Inputs: and Outputs: specification initially shows:
Inputs: List ; Attribute Name; Value ; [ StartIndex ]
Outputs: FoundIndex ; Instance
These entries are descriptive of the functional meaning of the inputs and outputs. They are capitalized to remind you that they are representational place holders. The actual value of the input and output depends on data flowing in and out of the primitive during program execution.
u Click the Types button. The Inputs: and Outputs: specification changes to:
Inputs: list ; string ; any ; [ integer ]
Outputs: integer ; instance | NULL
The data type specification of the inputs and outputs of the primitive are not capitalized to distinguish this information from the functional place holders. Some functional place holders are sufficiently explicit to let you guess what type of data the input or output handle. The left input, List, obviously takes a list input. But additional helpful information is supplied in the cases of the other roots and terminals.
In the find-instance Inputs: specification, the third item, any, means any Prograph data type value can be input to the Value terminal.
The Types button is especially useful when you get a runtime program error. To practice this technique:
u Dismiss the ˙Info… dialog.
u Create a universal method, called test, that feeds three strings into the choose primitive:
 
u Execute the test method. An execution-method case window pops up with the choose operation icon *380*flashing*409* (it might be hidden by the Error Message dialog). An Error Message dialog automatically pops up if you have the Error Messages option turned on. If not, select*440* Last *638*Error…*506* in the Info menu to receive an explanation of the problem.
NOTE: While you are still learning the Prograph primitives, your most frequent mistake will probably be passing the wrong data into a terminal of a primitive. With increased experience, you will make fewer of these simple errors.
The error dialog explains that the choose primitive has received an input of an inappropriate type on the first terminal.
u Dismiss the dialog. Double-click the left terminal of the choose operation. A scroll list in the upper left corner of the Value window opens. It shows that string data has arrived on the offended terminal.
u Dismiss the Value window and double-click on the choose primitive to open the ˙Info… dialog. The choose primitive entry is selected and displayed.
u Click the*472* Types *1116*button to see what the choose primitive is expecting as input on TheCriterion terminal. The Inputs: specification tells you that the first terminal is expecting a boolean data value.
u Dismiss the dialog and double-click the first terminal of the choose operation. Type TRUE to replace the selected string, "myResponse", in the value pane of the Value window. Click OK to close the Value window.
NOTE: You are using a debugging technique of changing the data value flowing along the datalink during the current execution. Editing*1086* data values during execution is an alternative to actually reworking the method or methods that produce the incorrect data value. This lets you continue on with the rest of the current execution. You can later track down and correct the error-producing condition.
u Press Return to step through the test method execution. The corrected value flowing along the datalink is accepted by the choose operation, and the execution window closes. A dialog displaying Correct appears.
u Press Return to dismiss the dialog and end execution of the test method.
NOTE: You did not have to change the data type in the scrolling list of the Value window when you changed the value from "myResponse" to TRUE on the first terminal of the choose operation. This is because Prograph has an intelligent data-value *885*interpreter. It understands TRUE and FALSE as booleans. If you put parentheses around "myResponse", changing it to ("myResponse"), Prograph would interpret this as a one item list. This interpretation saves you from having to specify both the value and its data type when using Value windows.
*930*To override this automatic interpretation of values, you can use explicit formatting. "TRUE", for example, would be interpreted as a string of capital letters spelling TRUE rather than as the boolean value TRUE. And "(myresponse)" would be interpreted as a string which begins and ends with parentheses characters. (*1016*String-denoting quotation characters must be plain quotation marks, " ", not typographic quotation marks, “ ”.)
